home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / docs / iptut001 / iptut001.txt < prev    next >
Text File  |  1995-03-21  |  7KB  |  176 lines
  1. ************************************************************************
  2. * Jouni Miettunen * jon@stekt.oulu.fi * Oulu * Finland * Europe * 1995 *
  3.  
  4.         Intermediate Programmer Tutorial #001
  5.         Copyright (c) 1995 by Jouni Miettunen
  6.               Version 1 - 20 March 1995
  7.  
  8.         Critical Error (0x24) Handler
  9.  
  10. ** INTRODUCTION
  11.  
  12. There are two kind of interrupts in DOS: hardware interrupts generated
  13. by hardware devices, such as a printer or a disk drive, and software
  14. interrupts generated by system software and/or user applications. When
  15. an interrupt occurs, the execution of the user application is halted for
  16. a moment, the program environment stored and the interrupt served.
  17.  
  18. There is a thing called "interrupt vector table" that has pointers to
  19. all the Interrupt Service Routines (ISR). When an interrupt occurs, an
  20. ISR to handle it will be located in the interrupt vector table based on
  21. the number of the interrupt and system execution will continue with it.
  22. Hopefully the provided ISR will take care of the problem with grace and
  23. afterwards the user application execution can be continued where it was
  24. halted. Unfortunately this is not always the case.
  25.  
  26. Hardware interrupts usually signal a fatal error with the operation of
  27. peripheral devices and can cause the user program to crash, sometimes
  28. bringing down even the whole system. The most usual occurance of such an
  29. error is the dreaded message
  30.  
  31.     Not ready reading drive A
  32.     Abort, Retry, Fail?_
  33.  
  34. The purpose of this tutorial is to demonstrate how you can replace the
  35. default critical error (0x24) handler in the interrupt vector table and
  36. take care of the problem yourself. There is nothing worse than a program
  37. suddenly asking "Abort, Retry, Fail?", especially if it has a Graphical
  38. User Interface (GUI).
  39.  
  40. ** FUNCTION PROTOTYPES
  41.  
  42. The used functions were provided by Borland C/C++ compiler, but are
  43. supported by other DOS C/C++ compilers, too. With Microsoft C and QuickC
  44. please use _harderr, _hardresume and _hardretn function names. These
  45. functions are unique to DOS and cannot be ported to other systems.
  46.  
  47. #include <dos.h>
  48.  
  49. void harderr    ( int (*handler)(int error, int ax, int bp, int si)    );
  50. void hardresure    ( int command                        );
  51. void hardretn    ( int error                        );
  52.  
  53. Please remember that BIOS and DOS are mostly not reentrant. Within your
  54. ISR routines you better not call any functions using DOS BIOS calls eg.
  55. beware printf(). BIOS calls 0x01 to 0x0C and 0x59 should be safe to use.
  56.  
  57. ** HARDERR()
  58.  
  59. This function sets up as the new hardware interrupt 0x24 service routine
  60. your own function pointed by the function pointer *handler. It will be
  61. called whenever a hardware error occurs, which usually is a disk I/O
  62. error. The arguments are DOS error number and the values of AX, BP and
  63. SI registers. The handler may return the value
  64.  
  65.     0 - ignore the error and continue the user application
  66.     1 - retry whatever you tried to do
  67.     2 - abort the user application
  68.  
  69. Error is the DOS error value passed by the system to 0x24 handler
  70.  
  71.     0 - Write protect
  72.     1 - Unknown unit (source of error not known)
  73.     2 - Drive not ready
  74.     3 - Unknown command
  75.     4 - Data error (CRC)
  76.     5 - Bad request (lenght of "drive request structure")
  77.     6 - Seek error
  78.     7 - Unknown media type
  79.     8 - Sector not found
  80.     9 - Printer out of paper
  81.     A - Write fault
  82.     B - Read fault
  83.     C - General failure
  84.     D - reserved
  85.     E - reserved
  86.     F - Invalid disk change
  87.  
  88. If argument AX is negative ie. bit 15 is set, there was a device error
  89. and you'll have to find more info at the device driver header located at
  90. the memory address BS:SI. If word at (BS:SI + 4) is zero, there was a
  91. bad memory image of FAT. If the word is negative (bit 15 set), look at
  92. the word last 4 bits (bits 0-3 of 15) at the address told in BS:SI
  93.  
  94.     0001 - error in standard input
  95.     0010 - error in standard output
  96.     0100 - error in NULL device
  97.     1000 - error in clock device
  98.  
  99. If AX is not negative ie. bit 15 is not set, there was a disk error. The
  100. disk drive in question is identified at the low-order byte of AX (AX &
  101. 0xff), so that 0 == A drive, 1 == B drive, 2 == C drive etc. The high
  102. order byte of AX (AX & 0xff00) will give you some extra information
  103.  
  104.     15    0 == disk error (else ignore rest)
  105.     14    unused
  106.     13    1 == Ignore allowed
  107.     12    1 == Retry allowed
  108.     11    1 == Abort allowed
  109.     9-10    00 - DOS error
  110.         01 - FAT error
  111.         10 - directory error
  112.         11 - data area error
  113.     8    0 == read error, 1 == write error
  114.     7-0    disk drive
  115.         0 - A drive
  116.         1 - B drive
  117.         2 - C drive etc.
  118.  
  119. BP and SI arguments contain the segment and offset addresses of the
  120. failing device driver, if the error was a device driver error.
  121.  
  122. ** HARDRESUME()
  123.  
  124. This function is called inside your own critical error interrupt 0x24
  125. handler installed previously by harderr() function and it is used to
  126. return to DOS. The return value will tell what to do after returning
  127.  
  128.     0 - Ignore the error
  129.     1 - Retry the last operation
  130.     2 - Abort the program with 0x23 (Control-Break) interrupt call
  131.     3 - Fail the current DOS system call (MS-DOS 3.0 and higher)
  132.  
  133. ** HARDRETN()
  134.  
  135. This function should be called only within your previously installed ISR
  136. function and it is used to force a return from ISR to the application
  137. program directly after the point that triggered the interrupt service
  138. routine in the first place. The returned value should be an appropriate
  139. MS-DOS error value for the problematic I/O call and user program should
  140. be able to take care of it.
  141.  
  142. If error occured with DOS BIOS calls 0x37 or less, the function will
  143. return value 0xff. If the BIOS call was 0x38 or greater, the returned
  144. value will be the given value. If error occured during a BIOS call that
  145. has no way of returning any error code, the given value is ignored. If
  146. the return value is not 0xff, user application will think a DOS error
  147. occured instead of a hardware error.
  148.  
  149. ** SAMPLE
  150.  
  151. Please see the included sample programs for some info
  152. int24.c        Critical Error (0x24) handler sample program
  153. testdisk.c    Check if you can write on disk
  154.  
  155. ** DISCLAIMER
  156.  
  157. Please note I have written this tutorial in good faith, but I cannot
  158. guarantees its contents. I think it's all correct, that things really
  159. work this way and could be taken care of like this. If something goes
  160. wrong, that will be your problem, not mine. You have been warned.
  161.  
  162. Additions, fixes and spelling and grammar instructions are most welcome.
  163. Hope you could find this useful and that from now on there will be less
  164. programs crashing due missing disks. This tutorial is copyrighted, but
  165. freely redistributable material.
  166.  
  167. ** AUTHOR
  168.  
  169.     Mr. Jouni Miettunen
  170.     Rautatienkatu 20 A 10
  171.     FIN-90100 OULU
  172.     FINLAND - EUROPE
  173.  
  174. * Jouni Miettunen * jon@stekt.oulu.fi * Oulu * Finland * Europe * 1995 *
  175. ************************************************************************
  176.